Create manifest

The manifest (referred to as an 'instance') is a container for a set of delivery instructions and their respective attributes. Each manifest instance contains one or more delivery objects, referred to as 'shipments'.

In this example we will start with a basic 'manifest instance' and a single 'shipment'. More complex delivery options are provided in subsequent examples.

Note on CARRIER_ID

The CARRIER_ID is a unique identifier for your carrier account. It is provided to you by Peddler.

Create a manifest instance

In order to create a manifest instance, you will need to make a POST request to the following endpoint:

/api/Carriers/[CARRIER_ID]/createShipments

The request body should contain a JSON encoded array of objects where each object corresponds to a shipment with the following properties:

https://alphadev-api.peddler.com/

Parameter	Type	Format	Description
`metaData`	REQUIRED	string	A unique ID for you to identify the individual shipment and to avoid duplication of shipments within our system
`senderAddress`	OPTIONAL	object	Address object containing sender details pertaining to delivery
`deliveryAddress`	REQUIRED	object	Address object containing consignee details pertaining to delivery
`deliveryAddress.company`	OPTIONAL	string	Include the company name
`deliveryAddress.name`	RECOMMENDED	string	Include the consignee name
`deliveryAddress.house`	RECOMMENDED	string	Include the house number unless included in `address1` field
`deliveryAddress.address1`	REQUIRED	string	Include street and house number unless house number is included in `house` field
`deliveryAddress.address2`	RECOMMENDED	string	Include any additional address information
`deliveryAddress.city`	REQUIRED	string	A valid city name
`deliveryAddress.state`	RECOMMENDED	string	State name
`deliveryAddress.postCode`	REQUIRED	string	If your country code is `NL`, you provide a valid Dutch 6PP postcode (PREFERRED) or 4PP postcode. 6PP postcode example: `1066EP` 4PP postcode example: `1066`
`deliveryAddress.country`	REQUIRED	string	ISO 3166-1 alpha-2 country code DEFAULT: `NL`
`deliveryAddress.phone`	RECOMMENDED	numeric	Customer mobile in E.164 format for SMS delivery notifications
`deliveryEmail`	RECOMMENDED	string	Email address for inflight options and delivery notifications
`deliveryShippingType`	RECOMMENDED	string	`PACKAGE` (DEFAULT) [higher rate], `LETTERBOX` [lower rate]
`deliveryContentsType`	RECOMMENDED	string	Possible values: `GOODS` (DEFAULT) `FOOD`, `ALCOHOL`, `BOOKS` or `ADR`
`shippingValue`	RECOMMENDED	numeric	Value of goods in shipment
`shippingValueCurrency`	RECOMMENDED	string	ISO 4217 currency code
`bundleId`	RECOMMENDED	string	A unique ID (if applicable) for the big box freight in case shipments are bundled together in a big box.
`colliMasterId`	RECOMMENDED	string	A unique ID (if applicable) for the colli which will be used to identify all packages (all collo) constituting the colli.
`colliCount`	RECOMMENDED	numeric	Number of packages (collo) constituting the colli.
`dimensions`	RECOMMENDED	string	Dimensions of the shipment. Example: `38.5cm * 35.5cm * 9.0cm`
`weight`	RECOMMENDED	numeric	Weight of the shipment
`weightUnit`	RECOMMENDED	string	Possible values: `KG` (DEFAULT), `LB`
`returnType`	RECOMMENDED	string	Possible values: `RETURN_TO_SENDER`, `RETURN_AND_DESTROY`, `RETURN_AND_DONATE`
`estimatedInjectionDate`	RECOMMENDED	string	JSON DATE ISO 8601 `2023-07-10T15:43:24.133Z` estimation when the shipment will be injected to destination distribution hub
`carrierOptions`	RECOMMENDED	object array	[ //Only when signature is required. //SURCHARGE maybe applicable { "key": "POD", "value": "SIGNATURE" }, //Required when shipping ADR goods { "key": "ADR", "value": "Description of ADR contents" }, //Required when OTP check is necessary for delivery //SURCHARGE maybe applicable { "key": "OTP", "value": "TRUE" } ]
`webhookUri`	RECOMMENDED	string	URI to receive webhook notifications. Each webhook can be unique to the shipment. Example: https://peddl.free.beeceptor.com/webhook/metadata
`serviceLevel`	RECOMMENDED	string	Possible values: `NEXT_DAY_48` (DEFAULT), `NEXT_DAY_60`, `SAME_DAY_24`, `SAME_DAY_SAT_24`, `SAME_DAY_SUN_24`, `EXPRESS_0900`, `EXPRESS_1030`, `EXPRESS_1200`, `EXPRESS_1700`, `EXPRESS_1800`, `EXPRESS_2200`, `EXPRESS_SAT`, `EXPRESS_SUN`, `INSTANT_02`

Note on carrierOptions

ADR

This requires additional description in carrierOptions

OTP

It is a 4-digit code sent to the consignee's email/mobile number for delivery verification.
The value TRUE in the carrierOptions array is a string and not a boolean.

Mock delivery shipment request

Blank fields

Any fields that are blank should NOT be included in the payload.

cURL
JavaScript

curl --location --globoff 'https://alphadev-api.peddler.com/api/Carriers/[CARRIER_ID]/createShipments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer nFzmOyturnztDiQT1gpijrgYczz2mBNW' \
--data-raw '[
    {
        "metaData": "UNIQUE_SENDER_REFERENCE_1",
        "deliveryAddress": {
            "name": "Peddler BV",
            "house": "12-46",
            "address1": "John M. Keynesplein",
            "address2": "B-toren, L.0.K.4",
            "city": "Amsterdam",
            "state": "Noord Holland",
            "postCode": "1066 EP",
            "country": "NL",
            "phone": "+31623754473"
        },
        "deliveryEmail": "[email protected]",
        "deliveryShippingType": "LETTERBOX",
        "deliveryContentsType": "GOODS",
        "shippingValue": 10,
        "shippingValueCurrency": "EUR",
        "dimensions": "38.5cm * 35.5cm * 9.0cm",
        "weight": "10",
        "weightUnit": "KG",
        "estimatedInjectionDate": "2023-07-10T15:43:24.133Z",
        "carrierOptions": [
          {
            "key": "POD",
            "value": "SIGNATURE"
          },
          {
            "key": "ADR",
            "value": "Description of ADR contents of package"
          }
        ],
        "webhookUri": "https://carrierwebsite.com/api/webhooks",
        "serviceLevel": "NEXT_DAY_48"
    }
]'

mockedDeliveryshipment.js
const mockedDeliveryshipment = [
    {
        "metaData": "UNIQUE_SENDER_REFERENCE_1",
        "deliveryAddress": {
            "name": "Peddler BV",
            "house": "12-46",
            "address1": "John M. Keynesplein",
            "address2": "B-toren, L.0.K.4",
            "city": "Amsterdam",
            "state": "Noord Holland",
            "postCode": "1066 EP",
            "country": "NL",
            "phone": "+31623754473"
        },
        "deliveryEmail": "[email protected]",
        "deliveryShippingType": "LETTERBOX",
        "deliveryContentsType": "GOODS",
        "shippingValue": 10,
        "shippingValueCurrency": "EUR",
        "dimensions": "38.5cm * 35.5cm * 9.0cm",
        "weight": "10",
        "weightUnit": "KG",
        "estimatedInjectionDate": "2023-07-10T15:43:24.133Z",
        "carrierOptions": [
          {
            "key": "POD",
            "value": "SIGNATURE"
          },
          {
            "key": "ADR",
            "value": "Description of ADR contents of package"
          }
        ],
        webhookUri: "https://carrierwebsite.com/api/webhooks",
        "serviceLevel": "NEXT_DAY_48"
    }
]

fetch('https://api-lokl.peddler.com/api/Carriers/CARRIER_ID/createShipments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(mockedDeliveryshipment)
})
.then(response => response.json())
.then(data => {
console.log(data);
})
.catch(error => {
console.error(error);
});

Minimum required fields

A shipment can be created with the minimum required fields, however, we recommend including as much information as possible to ensure a smooth delivery experience.

An example of a minimum required shipment is shown below:

minimumRequiredShipment.js
const mockedDeliveryshipment = [
    {
        "metaData": "UNIQUE_SENDER_REFERENCE_2",
        "deliveryAddress": {
            "address1": "John M. Keynesplein 12",
            "city": "Amsterdam",
            "postCode": "1066 EP",
            "country": "NL"
        }
    }
]

fetch('https://api-lokl.peddler.com/api/Carriers/CARRIER_ID/createShipments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(mockedDeliveryshipment)
})
.then(response => response.json())
.then(data => {
console.log(data);
})
.catch(error => {
console.error(error);
});

Mock delivery shipment response

Any validation errors would result in a 422 HTTP status code response, and validation errors in the response
The most common validation error is utilising a postcode not in our catchment area (we will provide a postcode validation example below)

mockedDeliveryshipmentResponse.json
[
    {
		"id": "XXXXXX1",
		"trackingNumber": "PDXXXXXXXXX1",
		"metaData": "UNIQUE_SENDER_REFERENCE_1",
		"status": "ADDED",
		"details": {
			"deliveryAddress": {
				"name": "Peddler BV",
				"house": "12-46",
				"address1": "John M. Keynesplein",
				"address2": "B-toren, L.0.K.4",
				"city": "Amsterdam",
				"state": "Noord Holland",
				"postCode": "1066 EP",
				"country": "NL",
				"phone": "+31623754473"
			},
			"deliveryEmail": "[email protected]",
			"deliveryShippingType": "LETTERBOX",
			"deliveryContentsType": "GOODS",
			"shippingValue": 10,
			"shippingValueCurrency": "EUR",
			"dimensions": "38.5cm * 35.5cm * 9.0cm",
			"weight": "10",
			"weightUnit": "KG",
			"estimatedInjectionDate": "2023-07-10T15:43:24.133Z",
			"carrierOptions": [{
					"key": "POD",
					"value": "SIGNATURE"
				},
				{
					"key": "ADR",
					"value": "Description of ADR contents of package"
				}
			],
			"webhookUri": "https://carrierwebsite.com/api/webhooks",
			"serviceLevel": "NEXT_DAY_48"
		}
	},
	{
		"id": "XXXXXX2",
		"trackingNumber": "PDXXXXXXXXX2",
		"metaData": "UNIQUE_SENDER_REFERENCE_2",
		"status": "ADDED",
		"details": {
			"deliveryAddress": {
				"name": "Peddler BV",
				"house": "12-46",
				"address1": "John M. Keynesplein",
				"address2": "B-toren, L.0.K.4",
				"city": "Amsterdam",
				"state": "Noord Holland",
				"postCode": "1066 EP",
				"country": "NL",
				"phone": "+31623754473"
			},
			"deliveryEmail": "[email protected]",
			"deliveryShippingType": "LETTERBOX",
			"deliveryContentsType": "GOODS",
			"shippingValue": 10,
			"shippingValueCurrency": "EUR",
			"dimensions": "38.5cm * 35.5cm * 9.0cm",
			"weight": "10",
			"weightUnit": "KG",
			"estimatedInjectionDate": "2023-07-10T15:43:24.133Z",
			"carrierOptions": [{
					"key": "POD",
					"value": "SIGNATURE"
				},
				{
					"key": "ADR",
					"value": "Description of ADR contents of package"
				}
			],
			"webhookUri": "https://carrierwebsite.com/api/webhooks",
			"serviceLevel": "NEXT_DAY_48"
		}
	},
	{
		"metaData": "UNIQUE_SENDER_REFERENCE_3",
		"status": "ERROR",
		"errorType": "INVALID_ADDRESS",
		"error": "Error: Address invalid [\"postcode missing\"]"
	},
	{
		"metaData": "UNIQUE_SENDER_REFERENCE_4",
		"status": "ERROR",
		"errorType": "INVALID_POSTCODE",
		"error": "Error: Postcode not available for delivery [\"postcode\"]"
	},
	{
		"metaData": "UNIQUE_SENDER_REFERENCE_5",
		"status": "ERROR",
		"errorType": "INVALID_FIELDS",
		"error": "Error: Required fields missing [\"metaData\"]"
	},
	{
		"metaData": "UNIQUE_SENDER_REFERENCE_6",
		"status": "ERROR",
		"errorType": "OTHER",
		"error": "Error: Duplicate meta data"
	}
]

Create a manifest instance​

ADR​

OTP​

Mock delivery shipment request​

Mock delivery shipment response​

Create a manifest instance

ADR

OTP

Mock delivery shipment request

Mock delivery shipment response